<!DOCTYPE html><html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Yoshimi User Manual ~ Command Line Interface</title>
    <link rel="stylesheet" type="text/css" href="files/style.css">
  </head>
  <body>
    <nav class="navbar">
      <a href="index.html">Index</a>
    </nav>
    <a id="top"></a>
    <h2 style="text-align: center">Command Line Interface</h2>
    <p>
    Yoshimi supplies a command line interface (CLI) that can perform any action that is available in the graphical interface (GUI). The CLI closely follows the GUi with respect to context levels.
    However, some control names are changed to enable shorter, unambiguous abbreviations to be used.
    <br><br>
    With Yoshimi installed, open a terminal window and type 'yoshimi' to start. Unless you have disabled the GUI it will also show, but the prompt you will see will be something like the following:
    <div class = "code">
Yoshimi 2.3.0 is starting
Using jack_audio for audio and alsa_midi for midi
Alsa midi priority is 39
Yoshimi 2.3.0
Build Number 2220
Clientname: yoshimi
Audio: jack -&gt; 'default'
Midi: alsa -&gt; 'Hua Xing:0, Komplete Audio 6:0'
Oscilsize: 512
Samplerate: 48000
Period size: 64

Yay! We're up and running :-)

Found 7284 instruments in 201 banks
Root 9. Bank set to 115 "The_Mysterious_Bank"
GUI refreshed
yoshimi>
    </div>
    A minor annoyance is that the GUI (if it is enabled) will take input focus as it opens, so you will have to click in the terminal window again to make further commands.
    <br><br>
    There are a number of commands that can be set at the time you start Yoshimi. Before starting you can view these with:
    <div class = "code">
music@devuan:~$ yoshimi --help
    </div>
    This doesn't actually start Yoshimi itself, but as you can see there are a lot of options available.The full list of options is:
    <div class = "code">
music@devuan:~$ yoshimi --help
Yoshimi 2.3.0 is starting
Usage: yoshimi [OPTION...]
            Yoshimi 2.3.0, a derivative of ZynAddSubFX - Copyright 2002-2009
            Nasca Octavian Paul and others, Copyright 2009-2011 Alan Calvert,
            Copyright 2012-2013 Jeremy Jongepier and others, Copyright
            2014-2023 Will Godfrey and others

  -a, --alsa-midi[=&lt;device&gt;] use alsa midi input
  -A, --alsa-audio[=&lt;device&gt;]   use alsa audio output
  -b, --buffersize=&lt;size&gt;    set internal buffer size
  -c, --no-cmdline           disable command line interface
  -C, --cmdline              enable command line interface
  -D, --define-root=&lt;path&gt;   define path to new bank root
  -i, --no-gui               disable gui
  -I, --gui                  enable gui
  -j, --jack-midi[=&lt;device&gt;] use jack midi input
  -J, --jack-audio[=&lt;server&gt;]   use jack audio output
  -k, --autostart-jack       auto start jack server
  -K, --auto-connect         auto connect jack audio
  -l, --load=&lt;file&gt;          load .xmz parameters file
  -L, --load-instrument=&lt;file&gt [@part];
                             load .xiz instrument file(no space)@n to part 'n'
  -M, --load-midilearn=&lt;file&gt;   load .xly file
      --null                 use Null-backend without audio/midi
  -N, --name-tag=&lt;tag&gt;       add tag to clientname
  -o, --oscilsize=&lt;size&gt;     set AddSynth oscillator size
  -R, --samplerate=&lt;rate&gt;    set alsa audio sample rate
  -S, --state[=&lt;file&gt;]       load .state complete machine setup file
  -S, --state[=<file>]             load .state complete machine setup file
  -u, --jack-session-file=&lt;file&gt;   load named jack session file
  -U, --jack-session-uuid=&lt;uuid&gt;   jack session uuid
  -?, --help                 Give this help list
      --usage                Give a short usage message

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.
music@devuan:~$
    </div>
    Many of these options can be stacked when you do start, such as:
    <div class = "code">
    yoshimi -b=128 -i -j
    </div>
    In the above example we are setting the buffer size to 128 frames, disabling the GUI and setting MIDI input to Jack. These settings only apply to the current instance, and don't change the stored ones.
    <br><br>
    Once running in the CLI you will be at the top level. Entering '<b>help</b>', or just a '<b>?</B>' will list all the available commands and also the names of the available contexts. If reporting is set for the CLI this will be paged as shown below.
    <div class = "code">
yoshimi&gt; ?
Commands:
  ?  Help                     show commands
  List                        list current settings
  STop                        all sound off
  RESet [s]                   return to start-up conditions, 'ALL' clear MIDI-learn (if 'y')
  EXit [s]                    tidy up and close Yoshimi (if 'y'), 'FOrce' instant exit regardless
  RUN &lt;s&gt;                     execute named command script forcing top level start
  RUNLocal &lt;s&gt;                execute named command script from current context level
    WAIT &lt;n&gt;                  1mS to 30,000mS delay, within script only
  ..                          step back one level
  /                           step back to top level

  Part [n1]   ...             - part operations
  VEctor [n1] ...             - vector operations
  SCale       ...             - scale (microtonal) operations
  MLearn [n1] ...             - MIDI learn operations
  COnfig      ...             - configuration settings
q=quit /=search PgUp/PgDown=scroll (line 1 of 65)
    </div>
    Quitting this pager will return you to the prompt, and it now shows the current context level.
    <div class = "code">
@ Top
yoshimi&gt;
    </div>
    Notice the odd capitalisation. This indicates the minimum abbreviation for the respective controls. Be aware that the same command doesn't always have the same minimum in other contexts.<br>
    <a href="#top" class="up">Back to top</a>
    <a id="vector"></a>
    <h3>Examples</h3>
     When entering the query on other context levels you will normally get the first few top level ones as a reminder these are available from <em>any</em> level. Other than that you will only see the commands (and deeper contexts) appropriate to that level. However, you can also specifically query a context from <em>any</em> point , in which case you will see the list for that one only, without changing your current position.
    <div class = "code">
@ p1+, Sub
yoshimi&gt; ? vector
Vector:
  &lt;n&gt;                         set current base channel
  [X/Y] CC &lt;n&gt;                CC n is used for X or Y axis sweep
  [X/Y] Features &lt;n&gt; [s]      sets X or Y features 1-4 (ON, Reverse, {other})
  [X] PRogram &lt;l/r&gt; &lt;n&gt;       X program change ID for LEFT or RIGHT part
  [Y] PRogram &lt;d/u&gt; &lt;n&gt;       Y program change ID for DOWN or UP part
  [X/Y] Control &lt;n1&gt; &lt;n2&gt;     sets n2 CC to use for X or Y feature n1 (2-4)
  OFF                         disable vector for this channel
  Name &lt;s&gt;                    text name for this complete vector

@ p1+, Sub
yoshimi&gt;
    </div>
    Another very useful command is '<b>list</b>' (or '<b>l</b>'). The command by itself just shows what lists are available. A full example listing the current MIDI learned CCs is shown below.
    <div class = "code">
@ Top
yoshimi&gt; l mlearn
Midi learned:
Line 1  CC 7  Chan 1  Part 1 Effect Send 1
Line 2  CC 81  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 1 Amplitude
Line 3  CC 82  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 3 Amplitude
Line 4  CC 83  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 2 Amplitude
Line 5  CC 84  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 4 Amplitude
Line 6  CC 85  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 6 Amplitude
Line 7  CC 86  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 8 Amplitude
Line 8  CC 87  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 10 Amplitude
Line 9  CC 88  Chan 1  Part 1 Kit 1 Add Voice 1 Harmonic 12 Amplitude
Line 10  CC 94  Chan 1  Main Master Mono/Stereo

@ Top
yoshimi&gt;
    </div>
    As a general rule '<b>?</b>' tells you what you can do and '<b>l</b>' tells you what has been set.
    <br><br>
    Many context levels have defaults that kick in if you don't add additional information. The most obvious being the <em>Part</em> level with just:
    <div class = "code">
@ Top
yoshimi&gt; set part
@ Part 1+
yoshimi&gt;
    </div>
    You not only see that it is on part 1 but the '+' indicates it's enabled. There are lots of hints like this. Also any context with numeric settings can be changed simply with the number:
    <div class = "code">
@ Part 1+
yoshimi&gt; set 5
@ Part 5
yoshimi&gt;
    </div>
    Note that part 5 has no '+' so is not enabled.
    <br><br>
    Many actions will stack if all the required context levels are active:
    <div class = "code">
@ Part 5
yoshimi&gt; s 1 add voice wave
@ p1+, A+, V1+ Sine
yoshimi&gt;
    </div>
    Here we used the minimum abbreviation for '<em>set</em>'. You will also see that not only have we jumped right up into the waveform context of Addsynth Voice 1, but that the current waveform is 'Sine' and all the earlier labels are now compressed so that the line doesn't get ridiculously long.
    <br><br>
    Other useful commands are:
    <ul>
      <li>
      <b>Read</b> The current value of the control.
      </li>
      <li>
      <b>MINimum</b> The minimum value.
      </li>
      <li>
      <b>MAXimum</b> The maximum value.
      </li>
      <li>
      <b>DEFault</b> The default value.
      </li>
    </ul>
    Instead of 'Read' you can use 'Get' but we don't recommend that. When working quickly it's easy for the <em>wrong</em> muscle memory to kick in so you mix up 'Set' and 'Get'.
    <br><br>
    Here is another sequence of commands:
    <div class = "code">
@ Top
yoshimi> s sys ec
System Effect 1 set to Echo
@ Sys eff 1 ECho-1
yoshimi> r del
System Effect 1 Echo Delay Value 35.000000
@ Sys eff 1 ECho-1
yoshimi> s del 40
System Effect 1 Echo Delay Value 40.000000
@ Sys eff 1 ECho-1?
yoshimi>  max del
Max 127 - learnable
@ Sys eff 1 ECho-1?
yoshimi>
    </div>
    Notice the '?' when you change the delay value. This is a warning that although the effect started with preset 1, you have now changed it. If you change either the preset or the effect itself, that setting will be lost.
    <br><br>
    Calling for the maximum also gave you the information that the control could be MIDI-learned.
    <br><br>
    The prompt can become 'stale' if there is a lot of activity from the GUI or via MIDI, but can be refreshed simply by hitting the '<em>return</em>' key, although it may be best to return to top level if you are not actively working.
    </p>
    <p>
    <a href="#vector">Back to Examples</a>
    <a href="#top" class="up">Back to top</a>
    </p>
  </body>
</html>
